home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 2 / Amiga Tools 2.iso / musik / dtl / dtlib.readme < prev    next >
Text File  |  1995-03-09  |  37KB  |  792 lines
  1.  
  2.         Documentation for the DES-Tracker Library System Release 2.00
  3.         =============================================================
  4.  
  5.                              as of Dec. 18, 1993
  6.  
  7.                           Written by Darren Schebek
  8.  
  9.          destracker.library, LScope, DTC, mJuke, and MODInfo are all
  10.                     Designed and written by Darren Schebek
  11.                     Copyright ©1992,1993 by Darren Schebek
  12.                              All rights reserved
  13.  
  14.  
  15. IMPORTANT NOTE:
  16.  
  17.     All versions of destracker.library v3.0 and above are incompatible with
  18. older versions, so any programs that use versions of the library older than
  19. v3.0 that wish to use the version in this release will have to be recompiled.
  20. I apologize for the inconvenience, but the library has now become much easier
  21. to use and much more powerful as a result of the enhancements introduced with
  22. the newer releases.
  23.  
  24.     Also, DES-Tracker has been rigorously tested with all types of display
  25. modes.  DES-Tracker works fine under all display modes (to the best of my
  26. knowledge) except for Euro 36 mode.  For some reason that I've have been
  27. unable to fathom, DES-Tracker will crash if used while with a Euro 36 display.
  28. If anyone has an idea as to why this might happen, then by all means let me
  29. know.
  30.  
  31.  
  32.  
  33.                                INTRODUCTION
  34.                                ============
  35.  
  36.     Music lovers!  Now you can enjoy the great sound of tracker music on your
  37. Amiga with a minimum of fuss.  DES-Tracker has been designed for low-memory
  38. platforms (like mine :).  The library is only 25K, the included jukebox
  39. program that uses the library is only 3.5K, and the library only requires an
  40. extra 2K in memory overhead (not including any loaded module, that is).  So
  41. you can be running the included jukebox program using a total of about 30K of
  42. fast mem.  Pretty slim.
  43.  
  44.     Programmers!  Now you can have the great sound of Tracker music in your
  45. programs with a minimum of fuss and your program can still be user friendly
  46. and elegant in nature!  Now you can have more control over syncing program
  47. events to music and have much more control over the music you play!  Even
  48. ARexx programmers can make full use of the library's powerful features and
  49. ample status information!
  50.  
  51.     This is the DES-Tracker library system.  The library does all the work for
  52. you and provides lots of helpful information about the song that it's playing
  53. as well.  This library system is NOT public domain.  However, it is freely
  54. distributable as long as it is distributed unmodified and in it's entirety,
  55. which includes the following files:
  56.  
  57. DTL/DTLib.ReadMe                    This file that you're reading now.
  58. DTL/ReadMe.Install                  How to install the library system.
  59. DTL/History.TXT                     A revision history of DES-Tracker.
  60. DTL/DTL0-Format.TXT                 Description of the DTL0 file format.
  61. DTL/FAQ.TXT                         Frequently asked questions about DES-Tracker.
  62. DTL/libs/destracker.library         The DES-Tracker library itself - v3.0.
  63. DTL/libs/req.library                Brand new (!) req.library v2.7! WB2.04-compat.
  64. DTL/c/DTC                           Lets you use the library from CLI - v2.0.
  65. DTL/c/LScope                        A visual scope that runs in the B/G - v2.0.
  66. DTL/c/LScope.info                   The .info file for the LScope program.
  67. DTL/c/mJuke                         A VERY small jukebox program. v2.0.
  68. DTL/c/MODInfo                       Displays information about a song module.
  69. DTL/docs/LibFuncs.DOC               Docs for the library functions.
  70. DTL/docs/RexxFuncs.DOC              Docs for the library's ARexx commands.
  71. DTL/docs/Structures.DOC             Docs for the custom library structures.
  72. DTL/rexx/Jukebox.rexx               A simple ARexx jukebox script example.
  73. DTL/rexx/Play.rexx                  A simple ARexx "load and go" script example.
  74. DTL/code/DTC.S                      Assembly source code for DTC program.
  75. DTL/code/LScope.S                   Assembly source code for LScope program.
  76. DTL/code/LScopePic.O                Object file for linking with LScope.
  77. DTL/code/mJuke.S                    Assembly source code for the mJuke program.
  78. DTL/code/JukeScript                 Example script for use with mJuke program.
  79. DTL/code/MODInfo.S                  Source code for the MODInfo program.
  80. DTL/include/clib/dtlib_protos.h     C prototype file
  81. DTL/include/pragmas/dtlib_pragmas.h C pragmas file for SAS/C.
  82. DTL/include/fd/dtlib.fd             C function definition file.
  83. DTL/include/libraries/dtlib.i       The include file for assembly language.
  84. DTL/include/libraries/dtlib.h       The include file for C.
  85. DTL/include/proto/dtlib.h           The main include file for C.
  86.  
  87.  
  88. PLEASE READ THE FOLLOWING CONDITIONS FOR USE OF THIS PRODUCT:
  89.  
  90.     You can use this library to your heart's desire, but if you use it in a
  91. commercial application, there is a fee.  The fee is a complimentary copy of
  92. the final program.  :)  It virtually goes without saying that I'm also
  93. interested in receiving non-commercial applications that use DES-Tracker as
  94. well.
  95.  
  96.     Of course, a monetary donation to the "Help-Darren-Get-A-Computer-That's-
  97. At-Least-PAL-Capable-And-Has-More-Than-One-Meg" fund would be greatly
  98. appreciated.  :)
  99.  
  100.     If you pass this DES-Tracker package on to others (which is encouraged)
  101. you must distribute the library package in its entirety (as previously
  102. mentioned) and each file must remain pristine (do not modify any of the files.
  103. Make copies for yourself and modify those instead).
  104.  
  105.     If you wish to distribute this library package incompletely (i.e., missing
  106. any files listed above) as *part of an application that uses it*, then you
  107. have my permission to do so under the following conditions:
  108.  
  109.     Condition #1:  You must provide a paragraph, either in the accompanying
  110.                    documentation or as part of the program's output, stating
  111.                    the following:
  112.  
  113.     "DES-Tracker and destracker.library Copyright (c)1992,1993 Darren Schebek"
  114.  
  115.  
  116.     Condition #2:  You must mention that your application does not contain the
  117.                    complete DES-Tracker package, and you should also include
  118.                    a word or two suggesting that interested users should pick
  119.                    up the complete DES-Tracker package.  OK, well, it would be
  120.                    nice if you could. :)
  121.  
  122.     Please remember that you use the DES-Tracker library and included programs
  123. at your own risk.  I assume no responsibility for any damage, data-loss, etc.
  124. that may be caused by DES-Tracker, either directly or indirectly.  Also note,
  125. however, that this release contains no known bugs (other than the Euro 36
  126. display mode crash bug mentioned previously).  However, DES-Tracker will cause
  127. serial and parallel contention if it runs using either of the CIA B timer
  128. interrupts.  This contention is eliminated when DES-Tracker manages to acquire
  129. a timer interrupt with the CIA A chip.  The included DTC program will tell you
  130. which CIA and which timer is being used by DES-Tracker.  You can also examine
  131. the library base structure to determine which CIA and timer is being used.
  132.  
  133.  
  134.     Here is a run-down of each file in this package:
  135.  
  136.  
  137. DTL/DTLib.ReadMe
  138. ----------------
  139.  
  140.     This is the text file that you are now reading.
  141.  
  142.  
  143. DTL/ReadMe.Install
  144. ------------------
  145.  
  146.     This text file simply mentions how to install the library system so that
  147. you can proceed to use it.
  148.  
  149.  
  150. DTL/History.TXT
  151. ---------------
  152.  
  153.     This is a text file containing a revision history of the DES-Tracker
  154. library package, including enhancements made for this release.
  155.  
  156.  
  157. DTL/DTL0-Format.TXT
  158. -------------------
  159.  
  160.     This is a text file that describes the DES-Tracker v1.0 file format (also
  161. known as the "DTL0" file format.  This file format was created by me for
  162. release 2.00 (library version 3.0) of DES-Tracker.  It's use is completely
  163. optional, but bear in mind that it's more efficient than Noisetracker,
  164. Protracker, and Soundtracker file formats.
  165.  
  166.     The reason I created this file format: I discovered a Protracker song
  167. that, when converted into Soundtracker v2.6 format, couldn't be converted into
  168. Soundtracker v2.6 format.  Since DES-Tracker kept (note: past tense) songs in
  169. memory in Soundtracker format, this was a bad thing.  Now, DES-Tracker keeps
  170. track of the song in memory in DES-Tracker v1.0 format.  Consequently, I
  171. thought I might as well support it as an actual file format.  It's only really
  172. useful if you have a huge Protracker song that you'd like to convert to
  173. Soundtracker format (so you can knock about 30K off its size) but can't
  174. because there would be too many unique patterns (Soundtracker can only handle
  175. up to 255 unique patterns).  The DES-Tracker v1.0 format can handle up to
  176. 65535 patterns, and it doesn't need a PSC0 construct, either.
  177.  
  178.  
  179. DTL/FAQ.TXT
  180. -----------
  181.  
  182.     This is a text file containing frequently asked questions about
  183. DES-Tracker.  Answers are also included as a bonus. :)
  184.  
  185.  
  186. DTL/libs/destracker.library
  187. ---------------------------
  188.  
  189.     This is the actual library itself.  The features of this library will be
  190. discussed later on, and is the main focus of the "LibFuncs.DOC" and
  191. "Structures.DOC" files.  The library currently understands Noisetracker v2.0
  192. format, Protracker v1.1a and up, Soundtracker v2.6 format, and DES-Tracker
  193. v1.0 format, and can read and write in all of these formats (the S/T v2.6
  194. format is much more efficient than Noisetracker or Protracker, and the
  195. DES-Tracker v1.0 format is even more efficient than ST v2.6).  I should also
  196. mention that the library also supports the Protracker extended "E" commands.
  197.  
  198.  
  199. DTL/libs/req.library
  200. --------------------
  201.  
  202.     This is the most recent version of Colin Fox's requester library (v2.7).
  203. It includes bug fixes for WB2.04.  The ARexx "Play.rexx" script uses it.
  204.  
  205.  
  206. DTL/c/DTC
  207. ---------
  208.  
  209.     Note:  This version of DTC (v2.0) will only function with version 3.0+ of
  210. destracker.library.
  211.  
  212.     DTC is a small program that you can use from a CLI window to feed commands
  213. to the library.  This program is pure code, i.e.,  it can be made resident
  214. using the "resident" command, or New WShell's "resi" command.  This program is
  215. just under 5700 bytes in size (quite small).  Due to the nature of libraries -
  216. they have a nasty tendency to be suddenly expunged whenever nobody is using
  217. them - it is best to first run the LScope program before using DTC.  That way,
  218. LScope will keep the library open.  DTC, when run, will open the library, give
  219. it the command(s) you specify, and then exit, closing the library.  If DTC is
  220. the only user of the library, then, when DTC runs and finishes, the library is
  221. closed and expungable, and will be expunged if the Amiga decides that it needs
  222. the extra memory used by the library (or if you run DPaint, which nobody does
  223. anymore now that Brilliance is available, except that the authors of
  224. Brilliance STILL leave the default coordinates as 0,0 when they save a brush -
  225. how completely inexcusable and irritating and...  oops, I've strayed somewhat
  226. off-topic.  Sorry).  With LScope running in the background, the library will
  227. always remain open between calls to DTC.
  228.  
  229.     To get a list of the commands that DTC supports, just run DTC from the
  230. command line without any arguments.
  231.  
  232.     DTC supports multiple commands in a single invocation.  Each command
  233. should be separated by a space character.  For example, if you wanted to use
  234. DTC to reset the library defaults, load a tune (called HamsterDance, for
  235. instance) and then start the song playing, you could invoke DTC once for each
  236. function, like so:
  237.  
  238.  DTC rd                         (reset default playback parameters)
  239.  DTC lm HamsterDance            (load the song file called "HamsterDance")
  240.  DTC bp
  241.  
  242. ...Instead, you can just type this:
  243.  
  244.  DTC rd lp HamsterDance         (Reset defaults, then Load & Play "HamsterDance")
  245.  
  246. ...which is much more economical.
  247.  
  248.   See the History.TXT file for details on changes made to DTC for this
  249. release.
  250.  
  251.  
  252. DTL/c/LScope
  253. ------------
  254.  
  255.     Note:  This version of LScope will only function with destracker.library
  256. v3.0 or higher (this release contains destracker.library v3.0).  If it can't
  257. find the right version of the library, or if there is insufficient memory
  258. available for LScope to run, then LScope will abort and give you back your
  259. command line prompt.  It doesn't tell you anything like "ERROR:  Insufficient
  260. Memory" because it detaches from the command line and consequently no longer
  261. has anywhere to send its output.
  262.  
  263.     Lscope is a visual scope program example for the library system.  You can
  264. run LScope from the CLI by typing "lscope" at the CLI prompt, or you can run
  265. it from a Workbench window by double-clicking on the LScope icon.  This
  266. program serves two purposes.  It is a great example of what you can do with
  267. the DES-Tracker library, and it's a useful tool for spying on the library to
  268. see what it's doing at any given time.  LScope runs in the background,
  269. automatically giving you back your command-line prompt after you run it.  The
  270. display runs at VBlank speed with minimal use of CPU time (which you can vary
  271. by altering LScope's task priority).  It is only around 25K bytes in length,
  272. and requires about 63K of memory total, including memory required for the
  273. display.  The LScope program is completely system friendly, allowing you to do
  274. whatever you like (e.g.,  modeming, programming, etc) at the same time that it
  275. is running.  It took me all of two days to write it in assembly language, but
  276. I've been making little changes to it here and there ever since.  :)
  277.  
  278.     This is version 2.0 of LScope, and it's very different from all previous
  279. versions.  See the History.TXT file for a list of the changes (not like they
  280. aren't obvious by just looking at it or anything :).
  281.  
  282.  
  283. DTL/c/LScope.info
  284. -----------------
  285.  
  286.     This is just the .info file for the LScope program so you can run LScope
  287. from a Workbench window.
  288.  
  289.  
  290. DTL/c/mJuke
  291. -----------
  292.  
  293.     Note:  mJuke will only function with version 3.0 or higher of
  294. destracker.library.  This is version 2.0 of mJuke.
  295.  
  296.     This program is for all you DES-Tracker users that don't have ARexx. :)
  297.  
  298.     This is a *very* small command-line-based jukebox program that I've
  299. written.  It's under 4K in size.  It can play all songs in a specified path,
  300. and can also process scripts of songs to play (in the "code" directory there
  301. is an example script called "JukeScript" that shows you how a script is set
  302. up).
  303.  
  304.     The mJuke program does not lock the library.  This is to allow you to
  305. invoke the DTC program to change playback volume (which the jukebox will then
  306. use while it's playing), unload the current module (causes the jukebox to
  307. proceed immediately to the next song in the list it intends to play, and other
  308. commands (but there's not much point in using DTC to load a module while the
  309. jukebox is playing). :)
  310.  
  311.     If the jukebox cannot load a given song for some reason - e.g., couldn't
  312. find the song file, not enough memory to load it, etc - then the jukebox will
  313. tell you so, and then proceed to the next song in the list automatically.
  314.  
  315.     You can abort the jukebox with CTRL-C, and pressing CTRL-F will skip the
  316. current song and go right on to the next one.  Note also that the source code
  317. for this program is included in the "code" directory.
  318.  
  319.     Please note that you shouldn't run mJuke more than once.  Besides, why
  320. would you go and do something like that?  That would be evil.
  321.  
  322.  
  323. DTL/c/MODInfo
  324. -------------
  325.  
  326.     This program is run from the CLI and will display all kinds of information
  327. about a module.  Try it!  If you do not specify a file to examine, then it
  328. will display info on any currently loaded module.  Otherwise, it will use
  329. DES-Tracker to load the mod, display info on it, and then unload the module
  330. and exit.
  331.  
  332.     MODInfo, as of this release, will tell you the calculated play time for
  333. the song in question as it would be played by the mJuke program (mentioned
  334. just above).
  335.  
  336.     MODInfo is currently in use on the Wizard Online BBS so that users can get
  337. all kinds of interesting information about a song (like play time, for
  338. instance) before they download it.  MODInfo detects and displays SampleTexts
  339. and even those inane comments that people trash instrument names with (why
  340. people do that, I just don't know, especially since SampleTexts can say so
  341. much more).
  342.  
  343.     This is version 2.00 of the MODInfo program.
  344.  
  345.  
  346. DTL/docs/LibFuncs.DOC
  347. ---------------------
  348.  
  349.     This text file contains documentation for each of the library's function
  350. calls.  Some might conjecture that this is a nifty file to have.
  351.  
  352.  
  353. DTL/docs/RexxFuncs.DOC
  354. ----------------------
  355.  
  356.     This text file contains documentation for each of the library's ARexx
  357. function calls.  There are about 50 of them, mostly because I haven't yet
  358. implemented auto-stem variable creation.  Perhaps in a future release...
  359.  
  360.  
  361. DTL/docs/Structures.DOC
  362. -----------------------
  363.  
  364.     This text file contains documentation on the custom library structures
  365. used by the DES-Tracker library, including the library base structure itself.
  366.  
  367.  
  368. DTL/rexx/Jukebox.rexx
  369. ---------------------
  370.  
  371.     A simple jukebox program written in ARexx.  Plays all modules in the given
  372. path in a random order.  What more could you want out of life?
  373.  
  374.  
  375. DTL/rexx/Play.rexx
  376. ------------------
  377.  
  378.     Another simple ARexx program.  This one just loads up the specified module
  379. and starts it playing.  Unlike the ARexx jukebox above, this program gives you
  380. back your command line prompt right away.  Requires req.library, which is
  381. included with this release of DES-Tracker.
  382.  
  383.  
  384. DTL/code/DTC.S
  385. --------------
  386.  
  387.     This is the assembly source code for the DTC program.  It's fairly easy to
  388. follow.  Although I originally wrote DTC (and everything else in this package)
  389. using Charlie Gibbs' A68K assembler, I have since switched to DevPac, since
  390. it's faster and more powerful.
  391.  
  392.  
  393. DTL/code/LScope.S
  394. -----------------
  395.  
  396.     This is the assembly source code for the LScope program.  After assembling
  397. it into an object file, you must link it with the LScopePic.O file, also
  398. included here.  If you want LScope to detach from the command line, then you
  399. must also link with cback.o (not included in this package).
  400.  
  401.     LScope.S is infested with comments.  Really.  Perhaps too many comments.
  402. It's almost irritating. =u)  This source code was created using DevPac.  The
  403. comments were created using coffee and cigarettes, and the headache was created
  404. by afterwards going to bed at 4:30am.
  405.  
  406.     The only parts that aren't really commented sufficiently are those dealing
  407. with the oscilloscope displays.  I just haven't had the time to go back and
  408. comment it.  The oscilloscope logic uses lots of unwound loop code, instanced
  409. with macros, which is why LScope is now about 25K in size.  This is not
  410. terribly efficient for a CPU with an instruction cache, but hey, I don't have
  411. an instruction cache.  Rewind the loop code, if you like.
  412.  
  413.  
  414. DTL/code/LScopePic.O
  415. --------------------
  416.  
  417.     This file is linked with LScope.O (created by assembling LScope.S) in case
  418. you actually want to assemble the LScope.S file (God help you).  :)
  419.  
  420.     I didn't include the original IFF picture for a couple of reasons.  One,
  421. it would just add unnecessarily to the size of the DES-Tracker package (of
  422. course, the ARexx jukebox program sort of falls into the same category.  Oh
  423. well :).  Secondly, to create the object file, I stripped the IFF header from
  424. the picture file and converted it into object file format using a custom
  425. utility of mine.  It would just get confusing if I were to include the program
  426. etc etc.  So I didn't.  If you want the LScope picture in an IFF format,
  427. you'll just have to use a screen grabber on it while it's running.
  428.  
  429.  
  430. DTL/code/mJuke.S
  431. ----------------
  432.  
  433.     This is the assembly language source code for the mJuke program.  It is a
  434. good example of using the library's event signalling capabilities.  This code
  435. does not need to be linked with any startup code, as it performs its own
  436. command-line argument parsing (which is another reason why the executable is
  437. less than 4K in size =u).  This source code was created with DevPac, and
  438. commented with glee.
  439.  
  440.  
  441. DTL/code/JukeScript
  442. -------------------
  443.  
  444.     This is an example script file that is understood by the mJuke program.
  445. Note that the mJuke program allows comments in the script file (prefixed with
  446. a semicolon).  You can create your own play scripts using this one as
  447. something to go by.
  448.  
  449.  
  450. DTL/code/MODInfo.S
  451. ------------------
  452.  
  453.     This is the source code for the MODInfo program.  I'm terribly sorry that
  454. I didn't have time to clean up the source or finish commenting it (I had to
  455. leave the country, but I'm back now and I guess I have no excuse for this
  456. now).  Anyway, it's pretty sloppy code and it's rather sparsely commented.
  457.  
  458.  
  459. DTL/include/clib/dtlib_protos.h
  460. -------------------------------
  461.  
  462.     This is the prototypes file.  It is only needed for applications written
  463. in C.
  464.  
  465.  
  466. DTL/include/pragmas/dtlib_pragmas.h
  467. -----------------------------------
  468.  
  469.     This is the pragmas file for use with SAS/C.
  470.  
  471.  
  472.  
  473. DTL/include/fd/dtlib.fd
  474. -----------------------
  475.  
  476.     This is the function definitions file used for creating pragmas.  It is
  477. only needed for applications written in C.
  478.  
  479.  
  480. DTL/include/libraries/dtlib.i
  481. -----------------------------
  482.  
  483.     This is the include file for assembly language applications.  If you're
  484. writing an assembly language program that uses the DES-Tracker library, you
  485. will need to include this file.
  486.  
  487.  
  488. DTL/include/libraries/dtlib.h
  489. -----------------------------
  490.  
  491.     This is the C version of the above include file.
  492.  
  493.  
  494. DTL/include/proto/dtlib.h
  495. -------------------------
  496.  
  497.     This is the file you include if you're writing a C application that uses
  498. the DES-Tracker library.  As well as defining the library base pointer
  499. (DesTrackerBase), this file will also include dtlib_pragmas.h and
  500. dtlib_protos.h for you.  Users should be aware that they will still need to
  501. include the standard "libraries.h" include file.
  502.  
  503.  
  504.  
  505.                         Features of destracker.library
  506.                         ==============================
  507.  
  508.     Here is a brief list of the functions supported by the DES-Tracker library
  509. and what they do (a more detailed explanation of these functions can be found
  510. in both the LibFuncs.DOC and RexxFuncs.DOC file):
  511.  
  512. Function Name:      What it does:
  513.  
  514. OwnPlayer           Lock out other programs from using the library.
  515. DisownPlayer        Allow others programs to use the library again.
  516. SetFilter           Turn low-pass filter on/off (Amiga power light).
  517. SetChannelEnable    Selectively enable/disable specific sound channels.
  518. SetStartPosition    Set the position in a song at which to begin a play seq.
  519. SetEndPosition      Set the position in a song at which to end a play seq.
  520. SetTemporalStart    Set the start position of a play sequence based on time.
  521. SetTemporalEnd      Set the end position of a play sequence based on time.
  522. SetTemporalPos      Set the current position of a play sequence based on time.
  523. SetIterations       Set the number of times to play a play sequence.
  524. PausePlaySeq        Temporarily suspend an active play sequence.
  525. ContinuePlaySeq     Resume a play seq. from the point at which it was paused.
  526. SetGlobalVolume     Set the global volume that music will play at.
  527. SetInstVolume       Set the default volume of a specific instrument.
  528. SetDefaultTempo     Set default tempo for the beginning of a play sequence.
  529. SetGlobalTempo      Set the global tempo for a song to play at.
  530. SetFineTempo        Set the global fine tempo for a song to play at.
  531. SetTimingMode       Set internal player timing to PAL (50Hz) or NTSC (60Hz).
  532. SetLoopIntent       Set/clear flag for whether a song is meant to loop or not.
  533. FadeGlobalVolume    Fade the global volume to a specific volume.
  534. SetVolumeFadeRate   Set the speed at which volume fades transpire.
  535. LoadModule          Load a song module into memory.
  536. UnloadModule        Release a song module from memory.
  537. BeginPlaySeq        Begin playing the predefined play sequence.
  538. VerifyModule        Determine if a disk file is a recognizable module format.
  539. SetModulePath       Add/remove a search path from library's linked list of paths.
  540. RetitleModule       Provide a new name for a module.
  541. ApplyGlobalTempo    Permanently alter a module's global tempo.
  542. SetCurPosition      Set the current play position in a loaded module.
  543. SaveModule          Save a module back to disk in Soundtracker v2.6 format.
  544. SetSaveFormat       Set format for SaveModule to use (Soundtracker/Noisetracker).
  545. SetAutoTiming       Turn on/off auto timing detection (not available yet).
  546. ResetDefaults       Reset library parameters to their default values.
  547. SetTempoInt         Set tempo interpretation mode (BPM / Non-BPM).
  548. AddStatusSignal     Add a status-event signal bit to library's signal queue.
  549. RemStatusSignal     Remove a signal bit from library's signal queue.
  550. StopPlaySeq         Stop playing current play sequence, reset to start position.
  551. InstallModule       "Loads" a module that resides in memory rather than on disk.
  552. CalcElapsedTime     Calculates how long a song will take to play.
  553. CalcVolFadeTime     Calculates the time that a volume fade will take.
  554.  
  555.     The above functions can be called from your own programs, regardless of
  556. what language you program in (provided that the language allows you to make
  557. calls to libraries, which is most likely).  The exception is ARexx, but of
  558. course, the DES-Tracker library has full ARexx support as well.
  559.  
  560.     As well as the many powerful functions listed above, DES-Tracker's library
  561. base structure contains *tons* of information regarding current play status
  562. (e.g. which instruments are being used *right now*, what note in what octave
  563. is currently playing in a given audio channel, etc).  It also tells you all
  564. sorts of things about the currently loaded module (its name, its size, what
  565. format it was in when it was loaded, how many instruments, etc).  It even
  566. keeps track of all instruments used in the currently loaded module, including
  567. the instrument names, default volumes, lengths, etc.  Tons of stuff.  Check
  568. out the "Structures.DOC" file in the "docs" directory if you don't believe me.
  569. :)
  570.  
  571.     You open the library for use in the same way that you'd open the Dos
  572. library or Intuition library (or any library, for that matter).  When you open
  573. the DES-Tracker library successfully, you get back a pointer to the
  574. DES-Tracker library base structure.  A pointer to the same instance of this
  575. structure is passed to all who open this library, and its elements are READ
  576. ONLY.  You must never write to them.  Never, never, ever.
  577.  
  578.  
  579.  
  580.                              The "PSC0" Construct
  581.                              ====================
  582.  
  583.     "PSC0" essentially means "Playback Status Construct".  Future versions of
  584. this construct (should the need arise to create them) will have the name
  585. "PSC1", "PSC2", etc, so if you are scanning a file looking for this construct
  586. for your own purposes, you should only check for "PSC" and then check the
  587. fourth character for a valid digit.
  588.  
  589.     Whenever you tell the DES-Tracker library to save a song module back to
  590. disk (using the SaveModule function, see LibFuncs.DOC), the library will also
  591. append extra information about the song at the very end of the song file (it
  592. is put at the very end so you can still load the song up into the Soundtracker
  593. v2.6, Noisetracker v2.0, or Protracker editors).  Note that the DES-Tracker
  594. v1.0 ("DTL0") file format will not have a PSC0 construct appended to it simply
  595. because it doesn't need one (that information is already an inherent part of
  596. the "DTL0" file format.  The PSC0 construct looks like this:
  597.  
  598.     ULONG   "PSC0"          The PSC0 Identifier.
  599.     ULONG   size            Size of the data portion of the PSC0 construct.
  600.     UBYTE   PBFlags         Playback flags (see below)
  601.     BYTE    FineTempo       Fine tempo setting (-128..127)
  602.     UBYTE   DefaultTempo    Default tempo of the song (0..31).
  603.     UBYTE   Iterations      Default number of iterations for song.
  604.  
  605.  
  606.     The size field contains the size of the entire PSC0 construct less the
  607. first two fields (i.e. "size" is currently 4).
  608.  
  609.     The PBFlags field contains the following flags:
  610.  
  611.     Bit 7: PF_LOOPINTENT    Set to 1 if this song is supposed to loop at the
  612.                             end (see Structures.DOC for an explanation of this
  613.                             flag as well as the SetLoopIntent function in
  614.                             LibFuncs.DOC).
  615.  
  616.     Bit 6: PF_TIMINGMODE    Set to 0 for 60Hz (NTSC), 1 for 50Hz (PAL) timing.
  617.  
  618.  
  619.     Bit 5: PF_TEMPOINT      Set to 0 if song uses "BPM" (Beats Per Minute)
  620.                             tempo interpretation. Set to 1 if song only uses
  621.                             normal tempos in 1..255 range.
  622.  
  623.     Bit 4: PF_NEWFINETEMPO  Set to 1 if fine tempo setting in this PSC0
  624.                             construct uses the new fine tempo system (as
  625.                             established by this release (r2.00, lib v3.0).
  626.                             Otherwise, fine tempo setting uses old fine tempo
  627.                             system.
  628.  
  629.     The FineTempo field contains the fine tempo setting at the time that the
  630. song module was saved.  Its range is -128..127.  A value of 0 is the default.
  631. Positive values cause an increase in global tempo.  Negative values cause a
  632. decrease in global tempo.
  633.  
  634.     The DefaultTempo field contains the default tempo setting for when the
  635. song first starts playing.  This is useful for songs that don't have any tempo
  636. commands in them (with songs like this, the ApplyGlobalTempo function won't
  637. work, see LibFuncs.DOC).  You can use the SetDefaultTempo function to set this
  638. parameter prior to saving a module to disk.
  639.  
  640.     The last field was unused in release 1.2 and earlier releases.  It's
  641. function now is to hold the default number of iterations for the song.  This
  642. is provided so that you can play a song from DTC and have it play a given
  643. number of times automatically.  A value of 0 here means iterate infinitely.
  644. It  might be worth noting that, with the introduction of the "Iterations"
  645. field, the Loop Intent bit in the playback flags is somewhat useless and
  646. obsolete (i.e., if Iterations is anything other than 1, then obviously the
  647. song is meant to loop).
  648.  
  649.     When you tell the library to save a module to disk, a PSC0 construct
  650. automatically gets appended to the end of the song file (unless you are saving
  651. in DES-Tracker v1.0 (DTL0) format, in which case a PSC0 construct is not
  652. needed).  The next time you load up the song, the library will detect the PSC0
  653. construct, extract the information from it and automatically set the
  654. respective parameters.
  655.  
  656.     Please bear in mind that if you load a module into the Soundtracker,
  657. Noisetracker or Protracker editors and the song has a PSC0 construct at the
  658. end of it, the editor will throw away this information.  So, if you then save
  659. the song from the editor, the PSC0 construct will be lost.
  660.  
  661.  
  662.  
  663.                                     WHEW!
  664.                                     =====
  665.  
  666.     Having said all that, I hope you enjoy using this library system.  I wrote
  667. the entire thing (DTC, LScope, mJuke, MODInfo, the library itself) in 100%
  668. assembly language using both Charlie Gibbs' a68k assembler and DevPac (I now
  669. use DevPac).  The assembly source code included in this package is meant to be
  670. compiled under DevPac.
  671.  
  672.     If you have any comments, criticisms, or suggestions (or just unbridled
  673. praise, ha ha), please let me know and help me to make this library system
  674. better and better.  I'd also *really* like to see any programs you write that
  675. use the DES-Tracker library (a deluge of scopes?  :).  You can reach me on
  676. usenet or by snail mail (see end of this file).  Have fun!
  677.  
  678.     I'd also like to say that, if you're using DES-Tracker and you can find it
  679. in the goodness of your heart, I'd really appreciate some kind of monetary
  680. donation.  I've spent an incredible amount of time designing, creating and
  681. improving DES-Tracker.  It'd be nice to get a donation or two.  :).  Is
  682. anybody reading this paragraph?  Hello...<tap> <tap> <tap>...is this thing on?
  683.  
  684.  
  685.  
  686.                                 SPECIAL THANKS
  687.                                 ==============
  688.  
  689.     I just gotta thank Gary Bonham at Oxxi, Inc. for suggesting that being
  690. able to know how long a song will take to play without actually having to play
  691. it would be a nifty idea.  After sweating over the time conversions,
  692. fractional precision and other math-y things, it came out well.  And it's a
  693. totally cool feature.  I know of no other player program or editor in
  694. existence that can do this.
  695.  
  696.     Thanks to Bruce Dawson (good friend, cool guy, and author of Mand-FXP and
  697. Mand 2000) who pulled me from the brink of insanity with a single hypothesis
  698. when my signalling code went mental on me.  :) What a great guy it is that he
  699. is.
  700.  
  701.     And hey!  I recently discovered how useful a playtester can be! =u)  Many
  702. thanks go to David Riley for pointing out an overwhelming number of bugs,
  703. documentation flaws, and include file glitches.  It appears that Dave is going
  704. to keep me up to my armpits in work for some time to come.  Do I thank him or
  705. do I hit him upside the head? =) =)  Just kidding.  It's mostly because of Dave
  706. that I got off my butt and started addressing some design issues that needed to
  707. be addressed.  This release of DES-Tracker is much more flexible and easier to
  708. get information out of as a result.  Thanks, Dave.
  709.  
  710.     Special thanks must also go to David Knox who brought a bug to my
  711. attention that occurred when DES-Tracker was used from within the Director II
  712. program.  I would not have found it for quite some time otherwise.  In return,
  713. I will give him a free plug. :)  David is head of the "Ready Robot Club"
  714. headquartered in Carmichael, California.  He publishes a monthly disk of
  715. educational games, stories and puzzles for kids from Kindergarten to Grade 6.
  716. He's been doing it for two years now, and has been mentioned in several
  717. magazines.  If you would like information about the Club, his address is as
  718. follows:
  719.                               David Knox
  720.                               P.O. Box 628
  721.                               Carmichael, CA
  722.                               95609-0628 U.S.A.
  723.  
  724.  
  725.     Thanks to Jason Johannson of Euphonix for creating the "Inherit The Stars"
  726. song module.  It showed me that it's possible for a module to exist that can't
  727. be converted into Soundtracker format from Protracker format.  It's because of
  728. this one single song module that I had to redesign and rewrite all my load &
  729. save code, and that the "DTL0" file format now exists.  So, do I thank Jason?
  730. Or do I hit him upside the head? :) :)
  731.  
  732.  
  733.     I feel I must also thank everybody who composes great Amiga tunes, as it
  734. was the excellent sound capabilities of the Amiga (and all these excellent
  735. tunes) that made me get an Amiga (I used to be an Atari ST owner, now it sits
  736. in the corner holding open the MIDI port on the Roland 5500).  :)
  737.  
  738.     My favorite tunes have changed now.  They are as follows:
  739.  
  740.         Most U4IA tunes (1993 is incredible!)
  741.         Most Maruku Buranu tunes (TechMaru is still a killer mod!)
  742.         Several tunes from Star Control II (Especially the Spathi Theme :)
  743.         Beyond Music
  744.         SuncoastDreamer/SpaceDebris (I've seen it under both names)
  745.         Lizard King
  746.         Die Hard
  747.  
  748.     Also many thanks to all those who prefer ProTracker over MED.  MED bites.
  749.  
  750.     And kudos to Ed Mackey (Ed-Player looks great, I love the buttons), but
  751. I wish he wouldn't condone destroying instrument names in favor of author
  752. comments (couldn't people at least use the unused instrument slots for that
  753. kind of thing?  Or better yet, use sampletexts.  Hell, if my MODInfo program
  754. can detect them, then so could Ed-Player).
  755.  
  756.     Special thanks and greetings to all of the members of Megawatts:
  757. Bosco, Lioth, Janne, Maruku, Reverb, RamChip, DanC, Idea, and Leviathan.  Have
  758. I forgotten anyone?  Hope you all have a great Christmas and New Year.  Greets
  759. to SpaZm (hey man, how's things goin'?)
  760.  
  761.     And a very special thanks to U4IA of MDMA.  The guy's given us *so* many
  762. incredible tunes.  I applaud his efforts and encourage others to stretch the
  763. limits of musical styles.  Be great!
  764.  
  765.     And I *still* don't know what the hell "Klisje Paa Klisje" means. :)
  766.  
  767.  
  768.                                WHAT'S IN STORE
  769.                                ===============
  770.  
  771.     - I'm still working on my IFF FORM TRKR specification and player code
  772.       (among other utilities in the works for it).  It's all starting to come
  773.       together now, so I must concentrate solely on the IFF stuff and,
  774.       unfortunately, pay less attention to DES-Tracker.  I'm still willing to
  775.       improve DES-Tracker, however, if someone will pay me to do it. :)
  776.  
  777.  
  778.                                           - Darren Schebek, Dec 18, 1993
  779.                                             (aka Gridlock of Megawatts)
  780.  
  781.  
  782. You can write to me here:       or contact me on usenet at:
  783.  
  784.     Darren Schebek                  dschebek@outb.wimsey.bc.ca
  785.     5620 Sherwood Blvd.
  786.     Delta, B.C.                 or call Wizard Online (official support BBS):
  787.     CANADA
  788.     V4L-2C5                     (604)322-3266 (2400 baud) or
  789.                                 (604)322-3232 (2400 baud) or
  790.                                 (604)322-3972 (14.4K baud)
  791.                                 (Sysop is Roger Earl)
  792.